第 N 章 · StoryCam 开发纪实

手绘旅行 VLOG：从产品方案到 PR 合并

本 session 围绕 StoryCam 新增第五个输入模式展开：把用户照片转成手绘旅行角色，再放进真实旅游地，生成带轻剧情的 VLOG。

日期：2026-05-13 类型：产品功能开发 / PR 修复 / 发布协作 状态：已 merge

本 Session 摘要

产品推进：在现有 4 个输入入口后新增第 5 个模式 手绘旅行 VLOG，明确它不是纯打卡合集，而是轻剧情旅行短片。
工作流约束：新模式必须继续走 StoryCam 主链路：输入、故事世界确认、资产图、核心分镜、扩展分镜、Seedance clip、final work。
视觉路线：角色来自用户照片和系统手绘参考图，场景来自真实旅游地路线资产板，最终是“真实背景 + 手绘角色”的混合风格。
工程闭环：创建分支、实现功能、补文档、提交 PR、处理 code review、通过 CI，并最终合并。
安全边界：明确不生成写实真人脸、不暴露 provider payload、不跳过确认环节，照片只用于手绘化外观参考。
协作方式：用户给出高密度产品计划，Codex 负责落地、验证、修复 review，并在用户明确要求后回复和 resolve GitHub thread。

时间线

1
用户原话 “现在默认输入有 4 个模式，我想再加 1 个不一样的。参考的步骤如 5 张图。”
Codex 总结 用户用教程截图说明产品方向：上传自己的照片，系统提供手绘风格参考图，通过以图生图得到手绘角色资产；旅游地则作为真实场景资产。截图的意义不是复刻教程 UI，而是提炼一种“真实旅行地 + 手绘角色”的内容生产方法。
影响：新模式的核心差异被定义为“人物资产手绘化，场景资产真实化”。
2
用户原话 “PLEASE IMPLEMENT THIS PLAN: 新增「手绘旅行 VLOG」输入模式……首版采用用户刚确认的方向：用户必须上传 1 张自己的照片，并指定旅游地；成片是轻剧情 VLOG，不是纯打卡合集。”
Codex 总结 需求被收束成可实现计划：新增模式 id handdrawn-travel-vlog，输入页增加旅行地字段和照片必填校验，API 类型增加 storyModeId 与 travelDestination，provider prompt 按模式分支，文档同步更新。
影响：产品方案转成了端到端工程任务，而不是单点 UI 改动。
3
用户原话 “[$code-simplifier] …… 建一个分支后，[$gstack-ship]”
Codex 总结 用户指定了开发姿态：先建分支，再按简洁实现和发布流程推进。Codex 在项目约束下执行，包括读取 StoryCam 的 AGENTS 规则、遵守“不跳过 story/script/asset/storyboard 确认”的产品非协商项，并准备进入 Ship Gate。
影响：本 session 从方案讨论进入可审查、可发布的工程分支。
4
用户补充 提供 StoryCam Agent Constitution：要求先读 docs，保持改动小、目标驱动、PR/Ship Gate 规则清楚，不能暴露 provider payload、签名 URL 或私密输入。
Codex 总结 Codex 根据项目宪法实施：新增 active exec plan，完成后归档；更新产品规格、前端说明、设计文档、API contract 和 provider contract；不新增数据库列，而是通过 script artifact 和资产数据持久化模式效果。
影响：功能被放入 StoryCam 既有架构，而不是绕开主流程另建一条捷径。
5
用户反馈 “有 code review”
Codex 总结 Codex 使用 GitHub review thread 工作流读取 PR #19 的未解决评论，发现两个 actionable 问题：OpenRouter 图片生成没有真正传递参考图；clip prompt packet 在多版本 session 中可能读取最早的 script，从而丢失新模式的视频约束。
影响：review 从“表面检查”进入具体根因修复。
6
用户意图 继续处理 review，并把 PR 推到可合并状态。
Codex 总结 Codex 修复了两个问题：为 OpenRouter image provider 增加 images 透传，并在 AI SDK 边界用 prompt object 携带图片；将 clip packet 的 script 选择改成按最新版本取值，并加入时间戳兜底排序。随后补充单测，跑过精准测试、pnpm typecheck、pnpm lint、pre-push 全量测试与 GitHub PR Fast Gate。
影响：问题完成“根因 -> 修复 -> 回归测试 -> CI 验证”的闭环。
7
用户原话 “需要回复下，并 resolve”
Codex 总结 在用户明确授权后，Codex 对两个 GitHub review thread 分别回复修复说明，并通过 GraphQL resolve。复查结果显示 review threads 共 2 个，未解决数量为 0。
影响：协作礼仪和工程状态同步完成，reviewer 能看到明确处理记录。
8
用户原话 “已经 merge”
Codex 总结 PR 合并完成。Codex 总结最终状态：review thread 已全部回复并 resolve，CI Fast Gate 通过，修复 commit 已进入分支并随 PR 合入。
影响：第五个输入模式从产品设想进入主线代码。

关键时刻

1. 新模式不是“旅行照片合集”

问题：如果只把用户角色放进旅游地，会变成打卡图集，和 StoryCam 的故事剧场定位不一致。

重要性：StoryCam 的北极星是私密故事影院，必须保留故事世界、分镜和视频确认链路。

处理：将新模式定义为“轻剧情 VLOG”，仍走 StoryCam 主链路，只改变输入和 prompt 视觉路线。

2. 用户照片只能用于手绘化参考

问题：用户上传自己的照片，容易滑向写实身份复刻或真人脸生成。

重要性：这关系到隐私、安全和产品风格边界。

处理：prompt 明确照片只用于发型、眼镜、穿搭轮廓、姿态和气质，不生成写实真人脸或身份复制。

3. OpenRouter 参考图透传是核心 bug

问题：资产 prompt 已经包含 images[]，但 OpenRouter provider 没有把图片传到 AI SDK。

重要性：若部署使用 OpenRouter 图片路径，新模式最关键的“照片生成手绘角色”会失效。

处理：在 OpenRouterImagePrompt、StoryCamGenerateImageInput 和 AI SDK 调用处完整透传图片，并加回归测试。

4. 多版本 script 必须取最新

问题：listBySession 按创建时间升序，旧逻辑会拿到第一个 ready script。

重要性：如果用户重新生成故事世界，新版 storyModeId 可能被旧 script 覆盖，视频 prompt 走错视觉路线。

处理：改为按版本号降序选择最新 script，并用更新时间和创建时间作为 tie-breaker。

5. Review 回复需要显式授权

问题：实现修复后，是否直接在 GitHub 回复和 resolve thread 属于写操作。

重要性：项目协作要求避免未经授权修改 review 状态。

处理：Codex 先修复并推送；用户说“需要回复下，并 resolve”后，才回复并 resolve 两个 thread。

工程证据

Branch
feat/handdrawn-travel-vlog
PR
#19 · https://github.com/nlp-zn/storycam/pull/19
Commits
0b2a9df feat: add handdrawn travel vlog mode
43b206e docs: document handdrawn travel vlog workflow
26258d7 fix: address handdrawn travel review feedback
Checks
pnpm lint passed
pnpm typecheck passed
精准测试：2 files / 11 tests passed
pre-push 全量测试：56 files / 300 tests passed
GitHub PR Fast Gate passed；Dev Integration Gate 与 Main Release Gate 在该 PR 运行中为 skipping
Review Threads
PRRT_kwDOSXDKHs6BfHXK：OpenRouter reference images 透传，已回复并 resolved
PRRT_kwDOSXDKHs6BfHXN：latest script artifact 选择，已回复并 resolved
复查结果：review threads 2，unresolved 0
主要文件
src/features/storycam/domain/storyModes.ts
src/server/ai/vercelAiClient.ts
src/lib/providers/openrouter/imageProvider.ts
src/server/storycam/clipPromptPacketService.ts
src/server/storycam/storyWorldAssetImageProviderFactory.ts
src/server/storycam/clipPromptPacketService.test.ts
src/lib/providers/openrouter/imageProvider.test.ts
以及产品规格、前端、设计、API contract、provider contract 相关文档
Merge
用户确认：“已经 merge”。合并后的具体 merge commit 未在本 session 中确认，待从仓库历史补充。
敏感信息
本 session 未记录 API key、token、cookie、完整签名 URL 或原始 provider payload；涉及私密素材和签名链接的内容在讲解中均按 [REDACTED] 原则处理。

对外讲解用总结

这一轮我们把 StoryCam 从“已有四种输入模式”推进到“支持手绘旅行 VLOG”的新创作入口。用户先用教程截图指出一个新的内容生产范式：用自己的照片生成手绘角色，再把角色放进真实旅游地。真正关键的产品判断，是没有把它做成一个旁路工具，而是让它完整进入 StoryCam 的故事世界、角色资产、场景资产、分镜、视频生成和最终作品链路。工程上，这意味着前端输入、API 类型、script artifact、资产 prompt、分镜 prompt、视频 prompt 和文档都要同时更新。PR review 又帮助发现两个会影响真实生成质量的问题：OpenRouter 路径漏传参考图，以及多版本 script 可能取旧模式。修复后通过测试、CI、review 回复与 resolve，最后 PR 合并。这个 session 连接了前面的产品探索和后续的主线能力扩展，是 StoryCam 从“故事短片工具”走向“用户可带入自己的风格化旅行记忆”的一次重要跃迁。

后续事项

已完成

  • 新增 handdrawn-travel-vlog 模式并接入 StoryCam 主链路。
  • 补齐输入校验、API 字段、provider prompt 分支和文档。
  • 修复 code review 指出的 OpenRouter 参考图透传和 latest script 选择问题。
  • PR review threads 已回复并 resolve，PR 已 merge。

待确认

  • 合并后的 merge commit、目标分支和发布版本号未在本 session 中明确记录。
  • 真实 provider 环境下的手绘角色生成质量，需要后续用非敏感测试素材验证。
  • 新模式上线后用户是否理解“轻剧情 VLOG”而非“旅游打卡合集”，仍需产品观察。

后续开发

  • 补充真实旅游地路线资产板的质量评估样例。
  • 观察 9:16 默认画幅与用户手动切换 16:9 的实际使用情况。
  • 继续强化隐私提示：照片只做手绘化参考，不做写实身份复刻。
  • 将本章节与其他 session HTML 按时间顺序合并成完整项目叙事文档。